gh-139452: Clarify redirect_stdout, stderr behavior #139490
Conversation
These don't "redirect" like a terminal where typically the file pointed to by fd 1 and 2 are made the "same" by the preparing process (ex. by `dup2` the given fd into that specific fd number). Rather, these context managers set the respective globals to the provided value. In most cases that should be a "file object".
|
@wolfgang-eder how does this look to you? |
|
Please limit the edit to just |
|
Thank you for improving the documentation. I am happy with the changes |
Doc/library/contextlib.rst
Outdated
| Similar to :func:`~contextlib.redirect_stdout` but redirecting | ||
| :data:`sys.stderr` to another file or file-like object. | ||
| Similar to :func:`~contextlib.redirect_stdout` but redirecting the global | ||
| :data:`sys.stderr` to another value, typically a :term:`file object`. |
There was a problem hiding this comment.
Maybe "another target" would be better here than "another value"?
|
@rhettinger to check my understanding: reduce to just the "file or file-like object." -> |
Doc/library/contextlib.rst
Outdated
| is hardwired to stdout. | ||
| is hardwired to :data:`sys.stdout`. This does not modify underlying file | ||
| objects or file descriptors. It sets the global :data:`sys.stdout` to the | ||
| provided value and at context exit sets it to the previous value. |
There was a problem hiding this comment.
This should be left out entirely. That is already covered by the docs for sys.stdout and sys.__stdout__
Doc/library/contextlib.rst
Outdated
| with open(os.devnull, 'w') as devnull: | ||
| with redirect_stdout(devnull): | ||
| help(pow) | ||
|
|
There was a problem hiding this comment.
I prefer that this be omitted as well. It stretches well beyond the original bug report. Also, it is not a practical example — the help function has no side-effects, so there is no reason to call it and ignore its output.
|
The docs for The tool is a minor convenience that looks a little nicer than an equivalent try/finally. Let's not make these context managers seem more complicated than they actually are. |
|
Thanks for the rationale! Will keep in mind for other docs changes I work on. Updated for the latest review round. |
These don't "redirect" like a terminal where typically the file pointed to by fd 1 and 2 are made the "same" (ex. by
dup2the given fd into that specific fd number). Rather, these context managers set the respective globals to the provided value. In most cases that should be a "file object".contextlib.redirect_stderr()#139452📚 Documentation preview 📚: https://cpython-previews--139490.org.readthedocs.build/